Norma de uso de la herramienta de gestión de cambios en BBDD en la Plataforma CI/CD corporativa

Ámbito de aplicación de la norma

La Junta de Andalucía tiene como objetivo estratégico la estandarización de las herramientas y normas corporativas para la homogeneización del ciclo de vida del desarrollo de un producto software, promoviendo las prácticas DevSecOps.

La gestión de cambios en bases de datos forma parte del ciclo de vida del desarrollo de aplicaciones, por lo que resulta necesario disponer de mecanismos que permitan gestionar estos cambios de forma controlada, trazable y automatizada.

Por tanto, el uso de la herramienta de gestión de cambios en bases de datos de la Plataforma de CI/CD corporativa DEBE ser usada por todo Sistema de Información que:

• se encuentre en el Proceso de Transición a DevSecOps
• se encuentre operativo o en desarrollo para ser desplegado en las infraestructuras de despliegue de la ADA, utilizando el modelo DevSecOps impulsado por el Servicio de Gobierno TI y Calidad.

Además, se RECOMIENDA  que la herramienta de gestión de cambios en bases de datos de la Plataforma de CI/CD corporativa sea usado por:

• Todo sistema de información de nuevo desarrollo.
• Cualquier otro sistema de información de la ADA, teniendo en cuenta sus posibles restricciones tecnológicas o presupuestarias.

Gobierno y obligatoriedad del uso

DIR_01 Uso de la herramienta para la gestión de cambios en bases de datos de la Plataforma CI/CD

OBLIGATORIO  La herramienta de gestión del cambios en bases de datos de la Plataforma CI/CD corporativa, es la herramienta que DEBEN utilizar los Sistemas de Información para la gestión de cambios en base de datos.

No se permitirá el uso de otras herramientas distintas para esta funcionalidad en la Plataforma de CI/CD corporativa.

DIR_02 Norma de uso de la Plataforma CI/CD corporativa

OBLIGATORIO  Se DEBEN cumplir todas las directrices descritas en la Norma de uso de la plataforma de integración y entrega continua corporativa.

La Norma de uso de la plataforma de integración y entrega continua corporativa es de aplicación al uso de la herramienta de gestión de cambios en bases de datos dentro de la Plataforma de CI/CD corporativa.

DIR_03 Prohibición de cambios manuales en bases de datos gestionadas

OBLIGATORIO  No se DEBEN realizar modificaciones manuales en bases de datos que estén gestionadas mediante la herramienta de gestión de cambios en bases de datos dentro del proceso de despliegue de la Plataforma de CI/CD corporativa.

Todos los cambios estructurales deben estar definidos mediante los changelogs y changesets correspondientes.

Organización técnica y configuración

DIR_04 Estructura de directorios y ficheros

OBLIGATORIO Los Sistemas de Información que utilicen la herramienta de gestión del cambios en bases de datos de la Plataforma CI/CD corporativa DEBEN estructurar los recursos asociados en el repositorio de código de cada componente siguiendo la estructura definida en la presente norma.

En la raíz del repositorio DEBE existir un directorio denominado “liquibase”

Dentro de este directorio DEBE existir una organización con los siguientes elementos:

• Un fichero de changelog raíz denominado “root_changelog.xml”, que actúa como punto de entrada para la ejecución de los cambios. Este fichero NO DEBE contener definiciones de changesets ni instrucciones de cambio directamente, sino incluir los changelogs versionados del proyecto mediante referencias explícitas (include).
• Un directorio denominado “changelogs” que contendrá los changelogs versionados del proyecto organizados en subdirectorios por versión. Los subdirectorios de changelogs DEBEN seguir la nomenclatura “changelog-<versión>”, donde “<versión>” corresponde a la versión del componente.
• Cada subdirectorio DEBE corresponderse con una versión del artefacto del componente.
• Dentro de cada subdirectorio de versión DEBEN existir los siguientes elementos:
  • Un fichero de changelog versionado cuyo nombre DEBE seguir la nomenclatura “changelog-<versión>.xml”, donde “<versión>” DEBE coincidir exactamente con la versión del componente. Este fichero agrupa los changesets y representa la evolución de la base de datos para dicha versión.
  • Los ficheros de changesets asociados a dicha versión. Estos ficheros DEBEN almacenarse directamente dentro del subdirectorio de versión correspondiente.
  • Los ficheros de changesets DEBEN seguir la nomenclatura “changeset-<versionChangelog>-<id>”, donde “<versionChangelog>” corresponde a la versión del changelog al que pertenecen. El identificador “<id>” DEBE ser único dentro del changelog y seguir una secuencia incremental que garantice el orden lógico de los cambios.

La estructura de directorios DEBE seguir un esquema similar al siguiente:

DIR_05 Configuración por entorno

OBLIGATORIO Se DEBEN definir ficheros de configuración independientes para cada entorno conforme a los entornos definidos en la Plataforma CI/CD corporativa en los que se ejecuten despliegues.

Estos ficheros DEBEN denominarse “liquibase-<entorno>.properties.enc”. Ejemplo: liquibase-pro.properties.enc

Como excepción, en entornos de pruebas podrá utilizarse un fichero en claro denominado liquibase-pru.properties, siempre que no contenga credenciales sensibles y se trate de un entorno controlado. El nombre de este fichero debe de ser: “liquibase-<entorno>.properties”. Ejemplo: liquibase-pru.properties

Los ficheros DEBEN permitir adaptar los parámetros de conexión y ejecución a las características específicas de cada entorno, garantizando su correcta integración en los procesos de despliegue automatizados.

DIR_06 Contenido mínimo del fichero de configuración

OBLIGATORIO Los ficheros de configuración DEBEN incluir: la URL de conexión a la base de datos, el usuario y contraseña de conexión.
Los ficheros liquibase-<entorno>.properties.enc DEBEN generarse a partir de un fichero liquibase.properties en claro. El fichero en claro NO DEBE almacenarse en el repositorio y DEBE ser encriptado previamente a su versionado (excepto en entornos de pruebas PRU, donde podrá utilizarse en texto claro siempre que no contenga credenciales sensibles). El fichero liquibase.properties utilizado como origen DEBE seguir una estructura homogénea que incluya, al menos, las siguientes propiedades:

Gestión de cambios en base de datos

DIR_07 Gestión de cambios mediante changesets

OBLIGATORIO Cada changeset DEBE incluir una o varias instrucciones técnicas para aplicar una modificación concreta en la base de datos.

Las operaciones de tipo DDL (definición de estructura) incluyen instrucciones como por ejemplo CREATE, ALTER, DROP, RENAME, etc., DEBEN definirse en changesets independientes.

Las operaciones de tipo DML (manipulación de datos) incluyen instrucciones como por ejemplo INSERT, UPDATE, DELETE, etc., PODRÁN agruparse en un mismo changeset cuando estén relacionadas funcionalmente.

Ejemplos de la agrupación de instrucciones:

• Un changeset que contenga varias instrucciones INSERT o UPDATE relacionadas funcionalmente será considerado válido.
• Un changeset que combine instrucciones de tipo ALTER (DDL) con instrucciones de tipo UPDATE o INSERT (DML) NO será válido.

DIR_08 Gestión de reversión de cambios en bases de datos

OBLIGATORIO Los changesets definidos mediante la herramienta de gestión de cambios en bases de datos DEBEN incluir la lógica necesaria para revertir los cambios aplicados, permitiendo la recuperación ante incidencias durante los procesos de despliegue.

DIR_09 Integridad del historial de cambios en bases de datos

OBLIGATORIO Los changesets que hayan sido ejecutados en entornos definidos en la Plataforma de CI/CD corporativa, NO DEBEN ser modificados.

La modificación de un changeset ya ejecutado puede provocar inconsistencias entre el estado de la base de datos y el historial de cambios gestionado por la herramienta, comprometiendo la trazabilidad y la correcta ejecución de los despliegues. En caso de requerirse cambios adicionales, estos DEBEN definirse mediante nuevos changesets que reflejen la evolución del esquema de datos.

Uso de la herramienta y restricciones

DIR_10 Uso para gestión estructural de datos

OBLIGATORIO La herramienta de gestión de cambios en bases de datos DEBE utilizarse exclusivamente para la gestión de cambios estructurales y para la carga de volúmenes reducidos de datos necesarios para el correcto funcionamiento de la aplicación.

No se DEBE utilizar para cargas masivas de información.

Se considerará carga de datos reducida aquella que no suponga un volumen significativo de información ni impacte en el rendimiento del sistema, estando orientada a la inicialización de catálogos, datos de configuración o información de soporte a la aplicación.

DIR_11 Compatibilidad de bases de datos

OBLIGATORIO Las bases de datos utilizadas DEBEN corresponderse con aquellas que sean compatibles con la herramienta de gestión de cambios en bases de datos proporcionada en la Plataforma CI/CD corporativa en cada momento.

DIR_12 Formato de definición de changesets

OBLIGATORIO Los changesets DEBEN definirse utilizando un formato soportado por la herramienta de gestión de cambios en bases de datos (XML, SQL, YAML o JSON).

Control de versiones y trazabilidad

DIR_13 Versionado del componente asociado a cambios en base de datos

OBLIGATORIO Las modificaciones en la estructura de la base de datos gestionadas mediante la herramienta DEBERÁN estar asociadas a una versión del componente.

No es obligatorio que todas las versiones del componente incluyan cambios en la base de datos.

En ningún caso la versión de la base de datos podrá ser superior a la versión del componente.

Cada estado de la base de datos DEBE corresponderse con una versión concreta del componente y con el conjunto de changesets aplicados.

La gestión del versionado de la base de datos se realizará mediante el uso de tags, permitiendo identificar de forma unívoca el estado de la base de datos asociado a cada despliegue.

DIR_14 Gestión de cambios en repositorio y trazabilidad

OBLIGATORIO Los changelogs y changesets DEBEN almacenarse en el repositorio de código corporativo horizontal, dentro del repositorio del componente.

DIR_15 Nomenclatura y definición de changesets y changelogs

OBLIGATORIO Cada changeset DEBE disponer de un identificador único y un atributo de autor, que permitan su correcta identificación dentro del historial de cambios.

El atributo “author” es obligatorio y DEBE seguir la nomenclatura “nombre.apellido1.apellido2” en minúsculas, sin tildes, sin caracteres especiales y utilizando únicamente caracteres alfabéticos.

Los identificadores de los changesets DEBEN seguir la nomenclatura “<versionChangelog>-<número>”, donde: “<versionChangelog>” corresponde a la versión del changelog al que pertenece y “<número>” es un valor numérico incremental, comenzando en 1 para cada changelog.
Por ejemplo, el fichero changeset-1.0.0-1.xml deberá contener un changeset definido como <changeSet id="1.0.0-1" author="nombre.apellido1.apellido2">.